Creating Windows3

Creating windows from resources allows you to localize your application for different languages and to change the characteristics of your windows during application development by changing only the window resources.

All four functions, GetNewCWindow (GetNewCWindow) , GetNewWindow (GetNewWindow) , NewCWindow (NewCWindow) , and NewWindow (NewWindow) , can allocate space in your application's heap for the new window's window record. For more control over memory use, you can allocate the space yourself and pass a pointer when creating a window. In either case, the Window Manager fills in the data structure and returns a pointer to it.

GetNewCWindow

Creates a color window with the properties defined in the 'WIND' resource with a specified resource ID.



 
pascal WindowPtr GetNewCWindow (short windowID, 

                     void *wStorage,

                     WindowPtr behind);

windowID: The resource ID of the 'WIND' resource that defines the properties of the window.
wStorage: A pointer to memory space for the window record.; If you specify a value of nil for wStorage , the GetNewCWindow function allocates the window record as a nonrelocatable object in the heap. You can reduce the chances of heap fragmentation by allocating the memory your application needs for window records early in your initialization code. Whenever you need to create a window, you can allocate memory from your own block and pass a pointer to it in the wStorage parameter.
behind: A pointer to the window that appears immediately in front of the new window on the desktop.; To place a new window in front of all other windows on the desktop, specify a value of (WindowPtr)-1L . When you place a window in front of all others, GetNewCWindow removes the highlighting from the previously active window, highlights the newly created window, and generates the appropriate activate events. Note that if you create an invisible window in front of all others on the desktop, the user sees no active window until you make the new window visible (or make another window active).; To place a new window behind all other windows, specify a value of nil .

DESCRIPTION

The GetNewCWindow function creates a new color window from the specified window resource and returns a pointer to the newly created window record. You can use the returned window pointer to refer to this window in most Window Manager functions. If GetNewCWindow is unable to read the window or window definition function from the resource file, it returns nil .

The GetNewCWindow function looks for a 'wctb' resource with the same resource ID as that of the 'WIND' resource. If it finds one, it uses the window color information in the'wctb' resource for coloring the window frame and highlighting selected text.

If the window's definition function (specified in the window resource) is not already in memory, GetNewCWindow reads it into memory and stores a handle to it in the window record. It allocates space in the application heap for the structure and content regions of the window and asks the window definition function to calculate those regions.

To create the window, GetNewCWindow retrieves the window characteristics from the window resource and then calls the NewCWindow function, passing the characteristics as parameters.

The GetNewCWindow function creates a window in a color graphics port. Before calling GetNewCWindow , verify that Color QuickDraw is available. Your application typically sets up its own global variables reflecting the system setup during initialization by calling the Gestalt function. See Inside Macintosh: Overview for more information about establishing the local configuration.

SPECIAL CONSIDERATIONS

Note that the GetNewCWindow function returns a value of type WindowPtr , not CWindowPtr .

If you let the Window Manager create the window record in your application's heap, call DisposeWindow (DisposeWindow) to dispose of the window's window record. If you allocated the memory for the window record yourself and passed a pointer to the storage to GetNewCWindow , use the CloseWindow function (CloseWindow) to close the window and the Memory Manager routine DisposePtr to dispose of the window record.

GetNewWindow

Creates a new window from a window resource when Color QuickDraw is not available.



 
pascal WindowPtr GetNewWindow (short windowID, 

                     void *wStorage,

                     WindowPtr behind);

windowID: The resource ID of the 'WIND' resource that defines the properties of the window.
wStorage: A pointer to memory space for the window record.; If you specify a value of nil for wStorage , the GetNewWindow function allocates the window record as a nonrelocatable object in the heap. You can reduce the chances of heap fragmentation by allocating the memory your application needs for window records early in your initialization code. Whenever you need to create a window, you can allocate memory from your own block and pass a pointer to it in the wStorage parameter.
behind: A pointer to the window that appears immediately in front of the new window on the desktop.; To place a new window in front of all other windows on the desktop, specify a value of (WindowPtr)-1 L. When you place a window in front of all others, GetNewWindow removes the highlighting from the previously active window, highlights the newly created window, and generates the appropriate activate events. Note that if you create an invisible window in front of all others on the desktop, the user sees no active window until you make the new window visible (or make another window active).; To place a new window behind all other windows, specify a value of nil .

DESCRIPTION

The GetNewWindow function takes the same parameters as GetNewCWindow (GetNewCWindow) and returns a value of type WindowPtr . The only difference is that it creates a monochrome graphics port, not a color graphics port. The window record and graphics port record that describe monochrome and color graphics ports are the same size and can be used interchangeably in most Window Manager functions.

The GetNewWindow function creates a new window from the specified window resource and returns a pointer to the newly created window record. You can use the returned window pointer to refer to this window in most Window Manager functions. If GetNewWindow is unable to read the window or window definition function from the resource file, it returns nil .

If the window's definition function (specified in the window resource) is not already in memory, GetNewWindow reads it into memory and stores a handle to it in the window record. It allocates space in the application heap for the structure and content regions of the window and asks the window definition function to calculate those regions.

To create the window, GetNewWindow retrieves the window characteristics from the window resource and then calls the function NewWindow , passing the characteristics as parameters.

SPECIAL CONSIDERATIONS

If you let the Window Manager create the window record in your application's heap, call DisposeWindow (DisposeWindow) to dispose of the window's window record. If you allocated the memory for the window record yourself and passed a pointer to the storage to GetNewWindow , use the CloseWindow function (CloseWindow) to close the window and the DisposePtr routine (documented in Inside Macintosh: Memory ) to dispose of the window record.

NewCWindow

Creates a window with a specified list of characteristics.



 
pascal WindowPtr NewCWindow (void *wStorage, 

                     const Rect *boundsRect,

                     ConstStr255Param title, 

                     Boolean visible, 

                     short procID, 

                     WindowPtr behind, 

                     Boolean goAwayFlag, 

                     long refCon);

wStorage: A pointer to the window record. If you specify nil as the value of wStorage , NewCWindow allocates the window record as a nonrelocatable object in the application heap. You can reduce the chances of heap fragmentation by allocating memory from a block of memory reserved for this purpose by your application and passing a pointer to it in the wStorage parameter.
boundsRect: A pointer to a rectangle, given in global coordinates, that specifies the window's initial size and location. This rectangle becomes the port rectangle of the window's graphics port. For the standard window types, the boundsRect field defines the content region of the window. The NewCWindow function places the origin of the local coordinate system at the upper-left corner of the port rectangle.

Note

The NewCWindow function actually calls the QuickDraw function OpenCPort to create the graphics port. The bitmap, pen pattern, and other characteristics of the window's graphics port are the same as the default values set by OpenCPort , except for the character font, which is set to the application font instead of the system font.

title: A string that specifies the window's title.; If the title is too long to fit in the title bar, the title is truncated. If the window has a close box, characters are truncated at the end of the title; if there's no close box, the title is centered and truncated at both ends.; To suppress the title in a window with a title bar, pass an empty string, not nil , in the title parameter.
visible: A Boolean value indicating visibility status: true means that the Window Manager displays the window; false means it does not.; If the value of the visible parameter is true , the Window Manager draws a new window as soon as the window exists. The Window Manager first calls the window definition function to draw the window frame. If the value of the goAwayFlag parameter is also true and the window is frontmost (that is, if the value of the behind parameter is (WindowPtr)-1L) , the Window Manager instructs the window definition function to draw a close box in the window frame. After drawing the frame, the Window Manager generates an update event to trigger your application's drawing of the content region.; When you create a window, you typically specify false as the value of the visible parameter. When you're ready to display the window, you call the ShowWindow function ShowWindow .
procID: The window's definition ID, a value that specifies both the window definition function and the variation code within that definition function. For a list of possible values, see "Window Definition IDs" .
behind: A pointer to the window that appears immediately in front of the new window on the desktop.; To place a new window in front of all other windows on the desktop, specify a value of (WindowPtr)-1L . When you place a new window in front of all others, NewCWindow removes highlighting from the previously active window, highlights the newly created window, and generates activate events that trigger your application's updating of both windows. Note that if you create an invisible window in front of all others on the desktop, the user sees no active window until you make the new window visible (or make another window active).; To place a new window behind all other windows, specify a value of nil .
goAwayFlag: A Boolean value that determines whether the window has a close box. If the value of goAwayFlag is true and the window type supports a close box, the Window Manager draws a close box in the title bar and recognizes mouse clicks in the close region; if the value of goAwayFlag is false or the window type does not support a close box, it does not.
refCon: The window's reference constant, set and used only by your application.

DESCRIPTION

The NewCWindow function creates a window as specified by its parameters, adds it to the window list, and returns a pointer to the newly created window record. You can use the returned window pointer to refer to this window in most Window Manager functions. If NewCWindow is unable to read the window definition function from the resource file, it returns nil .

The NewCWindow function looks for a 'wctb' resource with the same resource ID as the 'WIND' resource. If it finds one, it uses the window color information in the 'wctb' resource for coloring the window frame and highlighting.

If the window's definition function is not already in memory, NewCWindow reads it into memory and stores a handle to it in the window record. It allocates space for the structure and content regions of the window and asks the window definition function to calculate those regions.

Storing the characteristics of your windows as resources, especially window titles and window items, makes your application easier to localize.

The NewCWindow function creates a window in a color graphics port. Creating color windows whenever possible ensures that your windows appear on color monitors with whatever color options the user has selected. Before calling NewCWindow , verify that Color QuickDraw is available. Your application typically sets up its own set of global variables reflecting the system setup during initialization by calling the Gestalt function. See the chapter Inside Macintosh: Overview for more information about establishing the local configuration.

Note that the function NewCWindow returns a value of type WindowPtr , not CWindowPtr .

SPECIAL CONSIDERATIONS

If you let the Window Manager create the window record in your application's heap, call DisposeWindow (DisposeWindow) to close the window and dispose of its window record. If you allocated the memory for the window record yourself and passed a pointer to NewCWindow , use the CloseWindow function (CloseWindow) to close the window and the DisposePtr function (documented in Inside Macintosh: Memory ) to dispose of the window record.

NewWindow

Creates a new window with the characteristics specified by a list of parameters when Color QuickDraw is not available.



 
pascal WindowPtr NewWindow (void *wStorage, 

                     const Rect *boundsRect,

                     ConstStr255Param title, 

                     Boolean visible, 

                     short theProc, 

                     WindowPtr behind, 

                     Boolean goAwayFlag,

                     long refCon);

wStorage: A pointer to the window record. If you specify nil as the value of wStorage , NewWindow allocates the window record as a nonrelocatable object in the heap. You can reduce the chances of heap fragmentation by allocating the storage from a block of memory reserved for this purpose by your application and passing a pointer to it in the wStorage parameter.
boundsRect: A pointer to a rectangle, given in global coordinates, which specifies the window's initial size and location. This rectangle becomes the port rectangle of the window's graphics port. For the standard window types, boundsRect defines the content region of the window. The NewWindow function places the origin of the local coordinate system at the upper-left corner of the port rectangle.

Note

The NewWindow function actually calls the QuickDraw function OpenPort to create the graphics port. The bitmap, pen pattern, and other characteristics of the window's graphics port are the same as the default values set by OpenPort , except for the character font, which is set to the application font instead of the system font. The coordinates of the graphics port's port boundaries and visible region are changed along with its port rectangle.

title: A string that specifies the window's title.; If the title is too long to fit in the title bar, the title is truncated. If the window has a close box, characters at the end of the title are truncated; if there's no close box, the title is centered and truncated at both ends.; To suppress the title in a window with a title bar, pass an empty string, not nil .
visible: A Boolean value indicating visibility status: true means that the Window Manager displays the window; false means it does not.; If the value of the visible parameter is true , the Window Manager draws a new window as soon as the window exists. The Window Manager first calls the window definition function to draw the window frame. If the value of the goAwayFlag parameter (described below) is also true and the window is frontmost (that is, if the value of the behind parameter is (WindowPtr(-1L ), the Window Manager instructs the window definition function to draw a close box in the window frame. After drawing the frame, the Window Manager generates an update event to trigger your application's drawing of the content region.; When you create a window, you typically specify false as the value of the visible parameter. When you're ready to display the window, you call the ShowWindow function ShowWindow .
theProc: The window's definition ID, which specifies both the window definition function and the variation code for that definition function. For a list of possible values, see "Window Definition IDs" .
behind: A pointer to the window that appears immediately in front of the new window on the desktop.; To place a new window in front of all other windows on the desktop, specify a value of (WindowPtr)-1L . When you place a new window in front of all others, NewWindow removes highlighting from the previously active window, highlights the newly created window, and generates activate events that trigger your application's updating of both windows. Note that if you create an invisible window in front of all others on the desktop, the user sees no active window until you make the new window visible (or make another window active).; To place a new window behind all other windows, specify a value of nil .
goAwayFlag: A Boolean value that determines whether or not the window has a close box. If the value of goAwayFlag is true and the window type supports a close box, the Window Manager draws a close box in the title bar and recognizes mouse clicks in the close region; if the value of goAwayFlag is false or the window type does not support a close box, it does not.
refCon: The window's reference constant, set and used only by your application.

DESCRIPTION

The NewWindow function takes the same parameters as NewCWindow and, like NewCWindow (NewCWindow) , returns a WindowPtr as its function result. The only difference is that NewWindow creates a window in a monochrome graphics port, not a color graphics port. The window record and graphics port record that describe monochrome and color graphics ports are the same size and can be used interchangeably in most Window Manager functions.

The NewWindow function creates a window as specified by its parameters, adds it to the window list, and returns a pointer to the newly created window record. You can use the returned window pointer to refer to this window in most Window Manager functions. If NewWindow is unable to read the window definition function from the resource file, it returns nil .

If the window's definition function is not already in memory, NewWindow reads it into memory and stores a handle to it in the window record. It allocates space for the structure and content regions of the window and asks the window definition function to calculate those regions.

Storing the characteristics of your windows as resources, especially window titles and window items, makes your application easier to localize.

SPECIAL CONSIDERATIONS

If you let the Window Manager create the window record in your application's heap, call DisposeWindow (DisposeWindow) to close the window and dispose of its window record. If you allocated the memory for the window record yourself and passed a pointer to NewWindow , use the CloseWindow function (CloseWindow) to close the window and the DisposePtr function (documented in Inside Macintosh: Memory ) to dispose of the window record.